Object Sample Atom Structure

An object sample atom describes a single object, including information about the default viewing angles and the view settings. The structure of an object sample atom is defined by the VRObjectSampleAtom data type:

typedef struct VRObjectSampleAtom {
    UInt16                              majorVersion;
    UInt16                              minorVersion;
    UInt16                              movieType;
    UInt16                              viewStateCount;
    UInt16                              defaultViewState;
    UInt16                              mouseDownViewState;
    UInt32                              viewDuration;
    UInt32                              columns;
    UInt32                              rows;
    Float32                             mouseMotionScale;
    Float32                             minPan;
    Float32                             maxPan;
    Float32                             defaultPan;
    Float32                             minTilt;
    Float32                             maxTilt;
    Float32                             defaultTilt;
    Float32                             minFieldOfView;
    Float32                             fieldOfView;
    Float32                             defaultFieldOfView;
    Float32                             defaultViewCenterH;
    Float32                             defaultViewCenterV;
    Float32                             viewRate;
    Float32                             frameRate;
    UInt32                              animationSettings;
    UInt32                              controlSettings;
} VRObjectSampleAtom, *VRObjectSampleAtomPtr;

majorVersion

The major version number of the file format.

minorVersion

The minor version number of the file format.

movieType

The movie controller type. See "Object Controller Types" for a description of the available movie controllers for object views.

viewStateCount

The number of view states of the object. A view state selects an alternate set of images for an object's views. The value of this field must be positive.

defaultViewState

The 1-based index of the default view state. The default view state image for a given view is displayed when the mouse button is not down.

mouseDownViewState

The 1-based index of the mouse-down view state. The mouse-down view state image for a given view is displayed while the user holds the mouse button down while the cursor is over an object movie.

viewDuration

The total movie duration of all image frames contained in an object's view. In an object that uses a single frame to represent a view, the duration is the image track's sample duration time.

columns

The number of columns in the object image array (that is, the number of horizontal positions or increments in the range defined by the minimum and maximum pan values). The value of this field must be positive.

rows

The number of rows in the object image array (that is, the number of vertical positions or increments in the range defined by the minimum and maximum tilt values). The value of this field must be positive.

mouseMotionScale

The mouse motion scale factor (that is, the number of degrees that an object is panned or tilted when the cursor is dragged the entire width of the VR movie image). The default value is 180.0.

minPan

The minimum pan angle, in degrees. The value of this field must be less than the value of the maxPan field.

maxPan

The maximum pan angle, in degrees. The value of this field must be greater than the value of the minPan field.

defaultPan

The default pan angle, in degrees. This is the pan angle used when the object is first displayed. The value of this field must be greater than or equal to the value of the minPan field and less than or equal to the value of the maxPan field.

minTilt

The minimum tilt angle, in degrees. The default value is +90.0. The value of this field must be less than the value of the maxTilt field.

maxTilt

The maximum tilt angle, in degrees. The default value is -90.0. The value of this field must be greater than the value of the minTilt field.

defaultTilt

The default tilt angle, in degrees. This is the tilt angle used when the object is first displayed. The value of this field must be greater than or equal to the value of the minTilt field and less than or equal to the value of the maxTilt field.

minFieldOfView

The minimum field of view to which the object can zoom. The valid range for this field is from 1 to the value of the fieldOfView field. The value of this field must be positive.

fieldOfView

The image field of view, in degrees, for the entire object. The value in this field must be greater than or equal to the value of the minFieldOfView field.

defaultFieldOfView

The default field of view for the object. This is the field of view used when the object is first displayed. The value in this field must be greater than or equal to the value of the minFieldOfView field and less than or equal to the value of the fieldOfView field.

defaultViewCenterH

The default horizontal view center.

defaultViewCenterV

The default vertical view center.

viewRate

The view rate (that is, the positive or negative rate at which the view animation in objects plays, if view animation is enabled). The value of this field must be from -100.0 through +100.0, inclusive.

frameRate

The frame rate (that is, the positive or negative rate at which the frame animation in a view plays, if frame animation is enabled). The value of this field must be from -100.0 through +100.0, inclusive.

animationSettings

A set of 32-bit flags that encode information about the animation settings of the object. See "Animation Settings" for a description of the constants you can use to specify a value for this field.

controlSettings

A set of 32-bit flags that encode information about the control settings of the object. See "Control Settings" for a description of the constants you can use to specify a value for this field.

Object Controller Types

The movieType field of the object sample atom structure specifies an object controller type, that is, the user interface to be used to manipulate the object.

QuickTime VR supports the following controller types:



 
enum ObjectUITypes {

    kGrabberScrollerUI                          = 1,

    kOldJoyStickUI                              = 2,

    kJoystickUI                                 = 3,

    kGrabberUI                                  = 4,

    kAbsoluteUI                                 = 5

};

Constant descriptions

kGrabberScrollerUI: The default controller, which displays a hand for dragging and rotation arrows when the cursor is along the edges of the object window.
kOldJoyStickUI: A joystick controller, which displays a joystick-like interface for spinning the object. With this controller, the direction of panning is reversed from the direction of the grabber.
kJoystickUI: A joystick controller, which displays a joystick-like interface for spinning the object. With this controller, the direction of panning is consistent with the direction of the grabber.
kGrabberUI: A grabber-only interface, which displays a hand for dragging but does not display rotation arrows when the cursor is along the edges of the object window.
kAbsoluteUI: An absolute controller, which displays a finger for pointing. The absolute controller switches views based on a row-and-column grid mapped into the object window.

Animation Settings

The animationSettings field of the object sample atom is a long integer that specifies a set of animation settings for an object node. Animation settings specify characteristics of the movie while it is playing. You can use these constants to specify animation settings:



 
enum QTVRAnimationSettings {

    kQTVRObjectAnimateViewFramesOn              = (1 << 0),

    kQTVRObjectPalindromeViewFramesOn           = (1 << 1),

    kQTVRObjectStartFirstViewFrameOn            = (1 << 2),

    kQTVRObjectAnimateViewsOn                   = (1 << 3),

    kQTVRObjectPalindromeViewsOn                = (1 << 4),

    kQTVRObjectSyncViewToFrameRate              = (1 << 5),

    kQTVRObjectDontLoopViewFramesOn             = (1 << 6),

    kQTVRObjectPlayEveryViewFrameOn             = (1 << 7)

};

Constant descriptions

kQTVRObjectAnimateViewFramesOn: If this bit is set, play all frames in the current view state.
kQTVRObjectPalindromeViewFramesOn: If this bit is set, play a back-and-forth animation of the frames of the current view state.
kQTVRObjectStartFirstViewFrameOn: If this bit is set, play the frame animation starting with the first frame in the view (that is, at the view start time).
kQTVRObjectAnimateViewsOn: If this bit is set, play all views of the current object in the default row of views.
kQTVRObjectPalindromeViewsOn: If this bit is set, play a back-and-forth animation of all views of the current object in the default row of views.
kQTVRObjectSyncViewToFrameRate: If this bit is set, synchronize the view animation to the frame animation and use the same options as for frame animation.
kQTVRObjectDontLoopViewFramesOn: If this bit is set, stop playing the frame animation in the current view at the end.
kQTVRObjectPlayEveryViewFrameOn: If this bit is set, play every view frame regardless of play rate. The play rate is used to adjust the duration in which a frame appears but no frames are skipped so the rate is not exact.

Control Settings

The controlSettings field of the object sample atom is a long integer that specifies a set of control settings for an object node. Control settings specify whether the object can wrap during panning and tilting, as well as other features of the node. The control settings are specified using these bit flags:



 
enum QTVRControlSettings {

    kQTVRObjectWrapPanOn                        = (1 << 0),

    kQTVRObjectWrapTiltOn                       = (1 << 1),

    kQTVRObjectCanZoomOn                        = (1 << 2),

    kQTVRObjectReverseHControlOn                = (1 << 3),

    kQTVRObjectReverseVControlOn                = (1 << 4),

    kQTVRObjectSwapHVControlOn                  = (1 << 5),

    kQTVRObjectTranslationOn                    = (1 << 6)

};

See the section "Control Settings" in Chapter 2, "QuickTime VR Manager," for a more complete description of these control settings.

Constant descriptions

kQTVRObjectWrapPanOn: If this bit is set, enable wrapping during panning. When this control setting is enabled, the user can wrap around from the current pan constraint maximum value to the pan constraint minimum value (or vice versa) using the mouse or arrow keys.
kQTVRObjectWrapTiltOn: If this bit is set, enable wrapping during tilting. When this control setting is enabled, the user can wrap around from the current tilt constraint maximum value to the tilt constraint minimum value (or vice versa) using the mouse or arrow keys.
kQTVRObjectCanZoomOn: If this bit is set, enable zooming. When this control setting is enabled, the user can change the current field of view using the zoom-in and zoom-out keys on the keyboard (or using the VR controller buttons).
kQTVRObjectReverseHControlOn: If this bit is set, reverse the direction of the horizontal control.
kQTVRObjectReverseVControlOn: If this bit is set, reverse the direction of the vertical control.
kQTVRObjectSwapHVControlOn: If this bit is set, exchange the horizontal and vertical controls.
kQTVRObjectTranslationOn: If this bit is set, enable translation. When this setting is enabled, the user can translate using the mouse when either the translate key is held down or the controller translation mode button is toggled on.